\author {Sven Goldt}
\title {The Linux Programmer's Guide}
\chapter {System calls}

 A system call is usually a request to the operating system (kernel) to
 do a hardware/system-specific or privileged operation.  As of
 Linux-1.2, 140 system calls have been defined.  System calls like
 close() are implemented in the Linux libc.  This implementation often
 involves calling a macro which eventually calls syscall().  Parameters
 passed to syscall() are the number of the system call followed by the
 needed arguments.  The actual system call numbers can be found in
 $<linux/unistd.h>$ while $<sys/syscall.h>$ gets updated with a new
 libc.  If new calls appear that don't have a stub in libc yet, you can
 use syscall().  As an example, you can close a file using syscall()
 like this (not advised):

\begin{verbatim}
#include <syscall.h>

extern int syscall(int, ...);

int my_close(int filedescriptor)
{
   return syscall(SYS_close, filedescriptor);
}
\end{verbatim}

 On the i386 architecture, system calls are limited to 5 arguments
 besides the system call number because of the number of hardware
 registers.  If you use Linux on another architecture you can check
 $<asm/unistd.h>$ for the \_syscall macros to see how many arguments
 your hardware supports or how many the developers chose to support.
 These \_syscall macros can be used instead of syscall(), but this is
 not recommended since such a macro expands to a full function which
 might already exist in a library. Therefore, only kernel hackers
 should play with the \_syscall macros.  To demonstrate, here is the
 close() example using a \_syscall macro.

\begin{verbatim}
#include <linux/unistd.h>

_syscall1(int, close, int, filedescriptor);
\end{verbatim}
 
 The \_syscall1 macro expands revealing the close() function.  Thus we
 have close() twice--once in libc and once in our program.  The return
 value of syscall() or a \_syscall macro is -1 if the system call
 failed and 0 or greater on success.  Take a look at the global
 variable errno to see what happened if a system call failed.

 The following system calls that are available on BSD and SYS V are
 not available on Linux: \\ audit(), auditon(), auditsvc(), fchroot(),
 getauid(), getdents(), getmsg(), mincore(), poll(), putmsg(),
 setaudit(), setauid().

\endinput
